Node / ReticulumProjects / MeshChatX.git / files / docs / meshchatx.md

Displaying Raw • View rendered • Download

Tc9d1d9# MeshChatX Architecture and Design

MeshChatX is a very heavily customized fork of Reticulum-Meshchat, it is vastly different under the hood.

Tc9d1d9## Goals and Constraints

Tff7b72- Keep a local-first runtime model that works on desktop and headless systems.

Tff7b72- Preserve Reticulum and LXMF semantics while improving UX and operational tooling.

Tff7b72- Support multi-identity usage in one runtime without cross-identity data leakage.

Tff7b72- Keep the backend and frontend independently testable.

Tff7b72- Run in constrained environments (single board devices, containers, AppImage/desktop).

Tc9d1d9## System Overview

At a high level, MeshChatX is a single-process Python service that:

Tff7b72- initializes identity-specific context and persistent state,

Tff7b72- exposes HTTP API and WebSocket endpoints for the frontend,

Tff7b72- serves the built frontend assets from a local public directory,

Tff7b72- manages LXMF/Reticulum interactions and higher-level features.

The frontend is a SPA built with Vite and mounted in the same runtime context as the API.

Tc9d1d9## Runtime Topology

Tc9d1d9### Backend Runtime

Tff7b72- Main entrypoint: Ta5d6ff`meshchatx/meshchat.py` (orchestration). Shared helpers live in Ta5d6ff`meshchatx/src/path_utils.py`, Ta5d6ff`meshchatx/src/ssl_self_signed.py`, and Ta5d6ff`meshchatx/src/env_utils.py`; Ta5d6ff`meshchat.py` re-exports them for compatibility.

Tff7b72- Web stack: Ta5d6ff`aiohttp` + Ta5d6ff`aiohttp_session`

Tff7b72- Realtime channel: WebSocket endpoints for UI updates and control flows

Tff7b72- Transport/security: HTTPS by default, optional HTTP, optional custom cert paths

Tc9d1d9### Frontend Runtime

Tff7b72- Source tree: Ta5d6ff`meshchatx/src/frontend`

Tff7b72- Build output: Ta5d6ff`meshchatx/public`

Tff7b72- Served by backend static routing

Tff7b72- Uses API + WebSocket for state hydration and live updates

Tc9d1d9### Optional Desktop Runtime

Tff7b72- Electron packaging/build scripts at repository root

Tff7b72- Backend binaries/resources are bundled for packaged desktop artifacts

Tc9d1d9## Core Backend Design

Tc9d1d9### 1) Application Shell

Ta5d6ff`ReticulumMeshChat` in Ta5d6ff`meshchatx/meshchat.py` is the orchestration layer. It owns:

Tff7b72- server lifecycle,

Tff7b72- route registration,

Tff7b72- identity context switching and teardown,

Tff7b72- shared process-level concerns (logging, crash recovery wiring, health checks).

It intentionally centralizes operational control so runtime state changes happen in a predictable order.

Tc9d1d9### 2) Identity-Scoped Context Model

Ta5d6ff`IdentityContext` in Ta5d6ff`meshchatx/src/backend/identity_context.py` encapsulates state for one identity:

Tff7b72- storage path rooted at Ta5d6ff`storage/identities/<identity_hash>/`,

Tff7b72- identity-local SQLite DB,

Tff7b72- identity-local LXMF router state,

Tff7b72- manager instances (messages, announces, docs, map, forwarding, tools, and more).

This boundary prevents accidental cross-identity writes and keeps teardown deterministic.

Tc9d1d9### 3) Manager-Centric Domain Logic

Feature logic is delegated to dedicated backend modules under Ta5d6ff`meshchatx/src/backend`:

Tff7b72- message handling and routing,

Tff7b72- announce management and trimming/limits,

Tff7b72- docs, maps, page nodes, telemetry, interfaces,

Tff7b72- forwarding aliases and propagation synchronization,

Tff7b72- utility handlers for RN-specific tooling.

The design intent is to keep transport/runtime orchestration in Ta5d6ff`meshchat.py` and business/domain behavior in dedicated managers. Optional **RNS log level** is configured with **`--rns-log-level`** or **`MESHCHAT_RNS_LOG_LEVEL`** (CLI overrides env when both are set).

Tc9d1d9### 4) Persistence Layer

Tff7b72- Storage engine: SQLite

Tff7b72- Access style: explicit SQL-oriented data access layer (no heavyweight ORM)

Tff7b72- Schema migration and integrity checks are integrated into startup and context setup.

The project favors predictable SQL behavior and explicit migration control, which helps with compatibility and debugging on diverse platforms.

Tc9d1d9## API and Realtime Design

Tc9d1d9### HTTP API

Tff7b72- Implemented as explicit Ta5d6ff`aiohttp` routes in Ta5d6ff`meshchat.py`

Tff7b72- Includes app status, auth, messaging, interfaces, docs/tools, and maintenance endpoints

Tff7b72- Static assets are served from the frontend build output directory

Tc9d1d9### WebSockets

Tff7b72- Used for low-latency frontend state updates

Tff7b72- Keeps UI responsive for message state transitions and live network events

Tc9d1d9### Session/Auth Flow

Tff7b72- Cookie sessions via encrypted storage

Tff7b72- Auth and access-attempt tracking integrated with IP/User-Agent aware controls

Tff7b72- Debug endpoints provide visibility into logs and access-attempt records

This is also very well tested, but I still would not recommend exposing MeshChatX to the internet.

Tc9d1d9## Security Model

MeshChatX defaults toward secure local operation:

Tff7b72- HTTPS/WSS enabled by default.

Tff7b72- Self-signed cert generation if identity-local cert files are absent.

Tff7b72- Optional custom cert/key pair when deployment needs managed TLS material.

Tff7b72- CORS and CSP

Tff7b72- Session encryption and defensive middleware.

Tff7b72- Access attempt persistence plus lockout/rate limiting strategy (when auth enabled).

Since its HTTPS/WSS other local apps cannot sniff the traffic as easily.

Tc9d1d9## Build and Packaging Strategy

MeshChatX supports multiple deployment forms from one source tree:

Tff7b72- source/development execution,

Tff7b72- Python package and wheel distribution,

Tff7b72- container images,

Tff7b72- Electron desktop builds for major platforms.

The design uses a shared backend codebase and frontend build artifacts so feature behavior remains consistent across packaging targets.

Tc9d1d9## Operations and Reliability

Reliability features include:

Tff7b72- crash recovery integration,

Tff7b72- startup integrity/database health checks,

Tff7b72- backup/restore and snapshot support,

Tff7b72- explicit teardown flows for multi-context and forwarding resources,

Tff7b72- status endpoint for orchestration and container probes.

Tc9d1d9## NomadNet pages and Mesh Server

The built-in **NomadNet** browser and **Mesh Server** (page nodes) support Micron (Ta5d6ff`.mu`), Markdown (Ta5d6ff`.md`), plain text (Ta5d6ff`.txt`), and sanitised static HTML (Ta5d6ff`.html`). Pages are registered under Ta5d6ff`/page/<name>` on each node’s destination.

Authoring rules, security constraints for HTML/CSS, and API behaviour are documented in **`nomadmesh_pages.md`** in the same docs bundle (also available under **Documentation** in the app when MeshChatX docs are populated).

Tc9d1d9## Extensibility Points

The most practical extension points today are:

Tff7b72- new API routes in backend routing sections,

Tff7b72- new manager modules under Ta5d6ff`meshchatx/src/backend`,

Tff7b72- frontend page/component additions wired through existing router/state patterns,

Tff7b72- new config surface through CLI flags + environment variables,

Tff7b72- schema extension through the existing migration/versioning approach.

When adding features, prefer:

Tff7b72- identity-scoped state over global mutable state,

Tff7b72- explicit migration/version changes for DB schema updates,

Tff7b72- endpoint-level tests plus focused manager unit tests.